home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / CrtPipelin.3 < prev    next >
Encoding:
Text File  |  1995-07-17  |  8.9 KB  |  296 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/CrtPipelin.3,v 1.7 93/04/09 11:53:47 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_CreatePipeline tclc
  206. .BS
  207. .SH NAME
  208. Tcl_CreatePipeline \- create one or more child processes, with I/O redirection
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. int
  214. \fBTcl_CreatePipeline\fR(\fIinterp, argc, argv, pidArrayPtr, inPipePtr, outPipePtr, errFilePtr\fR)
  215. .SH ARGUMENTS
  216. .AS Tcl_Interp **pidArrayPtr
  217. .AP Tcl_Interp *interp in
  218. Interpreter to use for error reporting.
  219. .AP int argc in
  220. Number of strings in \fIargv\fR array.
  221. .AP char **argv in
  222. Array of strings describing command(s) and I/O redirection.
  223. .AP int **pidArrayPtr out
  224. The value at \fI*pidArrayPtr\fR is modified to hold a pointer to
  225. an array of process identifiers.  The array is dynamically
  226. allocated and must be freed by the caller.
  227. .AP int *inPipePtr out
  228. If this argument is NULL then standard input for the first command
  229. in the pipeline comes from the current standard input.
  230. If \fIinPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  231. create a pipe, arrange for it to be used for standard input
  232. to the first command,
  233. and store a file id for writing to that pipe at \fI*inPipePtr\fR.
  234. If the command specified its own input using redirection, then
  235. no pipe is created and -1 is stored at \fI*inPipePtr\fR.
  236. .AP int *outPipePtr out
  237. If this argument is NULL then standard output for the last command
  238. in the pipeline goes to the current standard output.
  239. If \fIoutPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  240. create a pipe, arrange for it to be used for standard output from
  241. the last command, and store a file id for reading from that
  242. pipe at \fI*outPipePtr\fR.
  243. If the command specified its own output using redirection then
  244. no pipe is created and -1 is stored at \fI*outPipePtr\fR.
  245. .AP int *errFilePtr out
  246. If this argument is NULL then error output for all the commands
  247. in the pipeline will go to the current standard error file.
  248. If \fIerrFilePtr\fR is not NULL, error output from all the commands
  249. in the pipeline will go to a temporary file created by
  250. \fBTcl_CreatePipeline\fR.
  251. A file id to read from that file will be stored at \fI*errFilePtr\fR.
  252. The file will already have been removed, so closing the file
  253. descriptor at \fI*errFilePtr\fR will cause the file to be flushed
  254. completely.
  255. .BE
  256.  
  257. .SH DESCRIPTION
  258. .PP
  259. \fBTcl_CreatePipeline\fR processes the \fIargv\fR array and sets
  260. up one or more child processes in a pipeline configuration.
  261. \fBTcl_CreatePipeline\fR handles pipes specified with ``|'',
  262. input redirection specified with ``<'' or ``<<'', and output
  263. redirection specified with ``>'';  see the documentation for
  264. the \fBexec\fR command for details on these specifications.
  265. The return value from \fBTcl_CreatePipeline\fR is a count of
  266. the number of child processes created;  the process identifiers
  267. for those processes are stored in a \fImalloc\fR-ed array and
  268. a pointer to that array is stored at \fI*pidArrayPtr\fR.
  269. It is the caller's responsibility to free the array when finished
  270. with it.
  271. .PP
  272. If the \fIinPipePtr\fR, \fIoutPipePtr\fR, and \fIerrFilePtr\fR
  273. arguments are NULL then the pipeline's standard input, standard
  274. output, and standard error are taken from the corresponding
  275. streams of the process.  Non-NULL values may be specified for
  276. these arguments to use pipes for standard input and standard
  277. output and a file for standard error.  \fBTcl_CreatePipeline\fR
  278. will create the requested pipes or file and return file identifiers
  279. that may be used to read or write them.  It is the caller's
  280. responsibility to close all of these files when they are no
  281. longer needed.  If \fIargv\fR specifies redirection for standard
  282. input or standard output, then pipes will not be created even
  283. if requested by the \fIinPipePtr\fR and \fIoutPipePtr\fR
  284. arguments.
  285. .PP
  286. If an error occurs in \fBTcl_CreatePipeline\fR (e.g. ``|'' or
  287. ``<'' was the last argument in \fIargv\fR, or it wasn't possible
  288. to fork off a child), then -1 is returned
  289. and \fIinterp->result\fR is set to an error message.
  290.  
  291. .SH "SEE ALSO"
  292. \fBTcl_DetachPids\fR, \fBTcl_ReapDetachedProcs\fR
  293.  
  294. .SH KEYWORDS
  295. background, child, detach, fork, process, status, wait
  296.